# utils.py
import traceback
from typing import Callable
import functools  # 导入 functools
import inspect


def safe_tool(func: Callable) -> Callable:
    """
    一个安全的工具装饰器，能够捕获执行过程中的所有异常，
    并保留原函数的签名信息，以便被 FastMCP 等框架正确解析。
    """

    @functools.wraps(func)  # 保留原函数签名和元数据
    def wrapper(*args, **kwargs):
        try:
            # 调用原始的、被装饰的函数
            return func(*args, **kwargs)
        except Exception as e:
            # 发生异常时，打印详细 Traceback 并抛出标准化的 MCP 错误信息
            tb = traceback.format_exc()
            print(f"❌ 工具 '{func.__name__}' 执行错误: {e}\n{tb}")
            # 向上抛出异常，FastMCP 会自动捕获并格式化为 MCP Error
            raise Exception(f"工具 '{func.__name__}' 执行失败: {e}")

    # 保留原始签名
    wrapper.__signature__ = inspect.signature(func)

    # 标记这个函数是一个 MCP 工具，以便动态加载器识别
    wrapper._is_mcp_tool = True

    return wrapper
